<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>uuid generator</title>
    <link rel="stylesheet" href="ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>uuid</h1>


<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>


<h2>Modules</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap'">
  <li><strong>uuid</strong></li>
</ul>
<h2>Topics</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap'">
  <li><a href="topics/readme.md.html">readme</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>uuid</code></h1>
<p>Copyright 2012 Rackspace (original), 2013 Thijs Schreijer (modifications)</p>

<p> Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.</p>
<p> You may obtain a copy of the License at</p>


<pre>
http://www.apache.org/licenses/LICENSE-<span class="number">2.0</span>
</pre>

<p> Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS-IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.</p>

<p> see http://www.ietf.org/rfc/rfc4122.txt</p>

<p> Note that this is not a true version 4 (random) UUID.  Since <code>os.time()</code> precision is only 1 second, it would be hard
 to guarantee spacial uniqueness when two hosts generate a uuid after being seeded during the same second.  This
 is solved by using the node field from a version 1 UUID.  It represents the mac address.</p>

<p> 28-apr-2013 modified by Thijs Schreijer from the original <a href="https://github.com/kans/zirgo/blob/807250b1af6725bad4776c931c89a784c1e34db2/util/uuid.lua">Rackspace code</a> as a generic Lua module.
 Regarding the above mention on <code>os.time()</code>; the modifications use the <code>socket.gettime()</code> function from LuaSocket
 if available and hence reduce that problem (provided LuaSocket has been loaded before uuid).</p>

<p> <strong>6-nov-2015 Please take note of this issue</strong>; <a href="https://github.com/Mashape/kong/issues/478">https://github.com/Mashape/kong/issues/478</a>
 It demonstrates the problem of using time as a random seed. Specifically when used from multiple processes.
 So make sure to seed only once, application wide. And to not have multiple processes do that
 simultaneously (like nginx does for example).</p>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#new">new (hwaddr)</a></td>
	<td class="summary">Creates a new uuid.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#randomseed">randomseed (seed)</a></td>
	<td class="summary">Improved randomseed function.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#seed">seed ()</a></td>
	<td class="summary">Seeds the random generator.</td>
	</tr>
</table>

<br/>
<br/>


    <h2 class="section-header "><a name="Functions"></a>Functions</h2>

    <dl class="function">
    <dt>
    <a name = "new"></a>
    <strong>new (hwaddr)</strong>
    </dt>
    <dd>

<p>Creates a new uuid.  Either provide a unique hex string, or make sure the
 random seed is properly set. The module table itself is a shortcut to this
 function, so <code>my_uuid = uuid.new()</code> equals <code>my_uuid = uuid()</code>.</p>

<p> For proper use there are 3 options;</p>

<ol>
    <li>first require <code>luasocket</code>, then call <code>uuid.seed()</code>, and request a uuid using no
    parameter, eg. <code>my_uuid = uuid()</code></li>
    <li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, set a random seed using <code>uuid.randomseed(some_good_seed)</code>,
    and request a uuid using no parameter, eg. <code>my_uuid = uuid()</code></li>
    <li>use <a href="index.html#">uuid</a> without <code>luasocket</code>, and request a uuid using an unique hex string,
    eg. <code>my_uuid = uuid(my_networkcard_macaddress)</code></li>
</ol>




    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">hwaddr</span>
         (optional) string containing a unique hex value (e.g.: <code>00:0c:29:69:41:c6</code>), to be used to compensate for the lesser <code>math_random()</code> function. Use a mac address for solid results. If omitted, a fully randomized uuid will be generated, but then you must ensure that the random seed is set properly!
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        a properly formatted uuid string
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example">
 <span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
 <span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
    </ul>

</dd>
    <dt>
    <a name = "randomseed"></a>
    <strong>randomseed (seed)</strong>
    </dt>
    <dd>
    Improved randomseed function.
 Lua 5.1 and 5.2 both truncate the seed given if it exceeds the integer
 range. If this happens, the seed will be 0 or 1 and all randomness will
 be gone (each application run will generate the same sequence of random
 numbers in that case). This improved version drops the most significant
 bits in those cases to get the seed within the proper range again.


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">seed</span>
         the random seed to set (integer from 0 - 2^32, negative values will be made positive)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        the (potentially modified) seed used
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example">
 <span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>)  <span class="comment">-- gettime() has higher precision than os.time()
</span> <span class="keyword">local</span> uuid = <span class="global">require</span>(<span class="string">"uuid"</span>)
 <span class="comment">-- see also example at uuid.seed()
</span> uuid.randomseed(socket.gettime()*<span class="number">10000</span>)
 <span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
    </ul>

</dd>
    <dt>
    <a name = "seed"></a>
    <strong>seed ()</strong>
    </dt>
    <dd>

<p>Seeds the random generator.
 It does so in 2 possible ways;</p>

<ol>
    <li>use <code>os.time()</code>: this only offers resolution to one second (used when
    LuaSocket hasn't been loaded yet</li>
    <li>use luasocket <code>gettime()</code> function, but it only does so when LuaSocket
    has been required already.</li>
</ol>







    <h3>Usage:</h3>
    <ul>
        <pre class="example">
 <span class="keyword">local</span> socket = <span class="global">require</span>(<span class="string">"socket"</span>)  <span class="comment">-- gettime() has higher precision than os.time()
</span> <span class="comment">-- LuaSocket loaded, so below line does the same as the example from randomseed()
</span> uuid.seed()
 <span class="global">print</span>(<span class="string">"here's a new uuid: "</span>,uuid())</pre>
    </ul>

</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
<i style="float:right;">Last updated 2015-11-09 10:26:13 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
